home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
FishMarket 1.0
/
FishMarket v1.0.iso
/
fishies
/
426-450
/
disk_447
/
tcl
/
tcl.man
< prev
next >
Wrap
Text File
|
1992-05-06
|
101KB
|
3,231 lines
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
NAME
Tcl - overview of tool command language facilities
INTRODUCTION
Tcl stands for ``tool command language'' and is pronounced
``tickle.'' It is actually two things: a language and a
library. First, Tcl is a simple textual language, intended
primarily for issuing commands to interactive programs such
as text editors, debuggers, illustrators, and shells. It
has a simple syntax and is also programmable, so Tcl users
can write command procedures to provide more powerful
commands than those in the built-in set.
Second, Tcl is a library package that can be embedded in
application programs. The Tcl library consists of a parser
for the Tcl language, routines to implement the Tcl built-in
commands, and procedures that allow each application to
extend Tcl with additional commands specific to that
application. The application program generates Tcl commands
and passes them to the Tcl parser for execution. Commands
may be generated by reading characters from an input source,
or by associating command strings with elements of the
application's user interface, such as menu entries, buttons,
or keystrokes. When the Tcl library receives commands it
parses them into component fields and executes built-in
commands directly. For commands implemented by the
application, Tcl calls back to the application to execute
the commands. In many cases commands will invoke recursive
invocations of the Tcl interpreter by passing in additional
strings to execute (procedures, looping commands, and
conditional commands all work in this way).
An application program gains three advantages by using Tcl
for its command language. First, Tcl provides a standard
syntax: once users know Tcl, they will be able to issue
commands easily to any Tcl-based application. Second, Tcl
provides programmability. All a Tcl application needs to do
is to implement a few application-specific low-level
commands. Tcl provides many utility commands plus a general
programming interface for building up complex command
procedures. By using Tcl, applications need not re-
implement these features. Third, Tcl will eventually
provide a mechanism for communicating between applications:
it will be possible to send Tcl commands from one
application to another. The common Tcl language framework
will make it easier for applications to communicate with one
another. The communication features are not implemented in
the current version of Tcl.
This manual page focusses primarily on the Tcl language. It
describes the language syntax and the built-in commands that
Page 1 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
will be available in any application based on Tcl. The
individual library procedures are described in more detail
in separate manual pages, one per procedure.
INTERPRETERS
The central data structure in Tcl is an interpreter (C type
``Tcl_Interp''). An interpreter consists of a set of
command bindings, a set of variable values, and a few other
miscellaneous pieces of state. Each Tcl command is
interpreted in the context of a particular interpreter.
Some Tcl-based applications will maintain multiple
interpreters simultaneously, each associated with a
different widget or portion of the application.
Interpreters are relatively lightweight structures. They
can be created and deleted quickly, so application
programmers should feel free to use multiple interpreters if
that simplifies the application. Eventually Tcl will
provide a mechanism for sending Tcl commands and results
back and forth between interpreters, even if the
interpreters are managed by different processes.
DATA TYPES
Tcl supports only one type of data: strings. All commands,
all arguments to commands, all command results, and all
variable values are strings. Where commands require numeric
arguments or return numeric results, the arguments and
results are passed as strings. Many commands expect their
string arguments to have certain formats, but this
interpretation is up to the individual commands. For
example, arguments often contain Tcl command strings, which
may get executed as part of the commands. The easiest way
to understand the Tcl interpreter is to remember that
everything is just an operation on a string. In many cases
Tcl constructs will look similar to more structured
constructs from other languages. However, the Tcl
constructs are not structured at all; they are just strings
of characters, and this gives them a different behavior than
the structures they may look like.
Although the exact interpretation of a Tcl string depends on
who is doing the interpretation, there are three common
forms that strings take: commands, expressions, and lists.
The major sections below discuss these three forms in more
detail.
BASIC COMMAND SYNTAX
The Tcl language has syntactic similarities to both the Unix
shells and Lisp. However, the interpretation of commands is
different in Tcl than in either of those other two systems.
Page 2 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
A Tcl command string consists of one or more commands
separated by newline characters or semi-colons. Each
command consists of a collection of fields separated by
white space (spaces or tabs). The first field must be the
name of a command, and the additional fields, if any, are
arguments that will be passed to that command. For example,
the command
set a 22
has three fields: the first, set, is the name of a Tcl
command, and the last two, a and 22, will be passed as
arguments to the set command. The command name may refer
either to a built-in Tcl command, an application-specific
command bound in with the library procedure
Tcl_CreateCommand, or a command procedure defined with the
proc built-in command. Arguments are passed literally as
text strings. Individual commands may interpret those
strings in any fashion they wish. The set command, for
example, will treat its first argument as the name of a
variable and its second argument as a string value to assign
to that variable. For other commands arguments may be
interpreted as integers, lists, file names, or Tcl commands.
Command names may be abbreviated as long as the abbreviation
is unique. However, it's probably a bad idea to use
abbreviations in command scripts and other forms that will
be re-used over time: changes to the command set may cause
abbreviations to become ambiguous, resulting in scripts that
no longer work. Abbreviations are intended primarily for
commands that are typed interactively, invoked once, and
discarded.
COMMENTS
If the first non-blank character in a command is #, then
everything from the # up through the next newline character
is treated as a comment and ignored.
GROUPING ARGUMENTS WITH BRACES
Normally each argument field ends at the next white space,
but curly braces (``{'' and ``}'') may be used to group
arguments in different ways. If an argument field begins
with a left brace, then the argument isn't terminated by
white space; instead it ends at the matching right brace.
Tcl will strip off the outermost layer of braces before
passing the argument to the command. This provides a simple
mechanism for including white space in arguments. For
example, the command
set a {This is a single argument}
Page 3 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
will pass two arguments to set: a and This is a single
argument. In the command
set a {xyz a {b c d}}
the set command will receive two arguments: a and xyz a {b c
d}.
When braces are in effect, the matching brace need not be on
the same line as the starting quote or brace; in this case
the newline will be included in the argument field along
with any other characters up to the matching quote or brace.
For example, the eval command takes one argument, which is a
command string; eval invokes the Tcl interpreter to execute
the command string. The command
eval {
set a 22
set b 33
}
will assign the value 22 to a and 33 to b.
When an argument is in braces, then command, variable, and
backslash substitutions do not occur as described below;
all Tcl does is to strip off the outer layer of braces and
pass the contents to the command.
If the first character of a command field isn't a left
brace, then neither left nor right braces in the field will
be treated specially (except as part of variable
substitution; see below).
COMMAND SUBSTITUTION WITH BRACKETS
If an open bracket occurs in any of the fields of a command,
then command substitution occurs. All of the text up to the
matching close bracket is treated as a Tcl command and
executed immediately. Then the result of that command is
substituted for the bracketed text. For example, consider
the command
set a [set b]
When the set command has only a single argument, it is the
name of a variable and set returns the contents of that
variable. In this case, if variable b has the value foo,
then the command above is equivalent to the command
set a foo
Brackets can be used in more complex ways. For example, if
Page 4 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
the variable b has the value foo and the variable c has the
value gorp, then the command
set a xyz[set b].[set c]
is equivalent to the command
set a xyzfoo.gorp
A bracketed command need not be all on one line: newlines
within brackets are treated as argument separators, not
command separators. If a field is enclosed in braces then
the brackets and the characters between them are not
interpreted specially; they are passed through to the
argument verbatim.
VARIABLE SUBSTITUTION WITH $
The dollar sign ($) may be used as a special shorthand form
for substituting variables. If $ appears in an argument
that isn't enclosed in braces then variable substitution
will occur. The characters after the $, up to the first
character that isn't a number, letter, or underscore, are
taken as a variable name and the string value of that
variable is substituted for the name. Or, if the dollar
sign is followed by an open curly brace then the variable
name consists of all the characters up to the next close
curly brace. For example, if variable foo has the value
test, then the command
set a $foo.c
is equivalent to the command
set a test.c
and the command
set a abc${foo}bar
is equivalent to the command
set a abctestbar
Variable substitution does not occur in arguments that are
enclosed in braces: the dollar sign and variable name are
passed through to the argument verbatim.
The dollar sign abbreviation is simply a shorthand form. $a
is completely equivalent to [set a]; it is provided as a
convenience to reduce typing.
Page 5 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
SEPARATING COMMANDS WITH SEMI-COLONS |
Normally, each command occupies one line (the command is |
terminated by a newline character). However, semi-colon |
(``;'') is treated as a command separator character; |
multiple commands may be placed on one line by separating |
them with a semi-colon.
BACKSLASH SUBSTITUTION
Backslashes may be used to insert non-printing characters
into command fields and also to insert special characters
like braces and brackets into fields without them being
interpreted specially as described above. The backslash
sequences understood by the Tcl interpreter are listed
below. In each case, the backslash sequence is replaced by
the given character:
\b Backspace (octal 10).
\e Escape (octal 33).
\n Newline (octal 15).
\t Tab (octal 11).
\{ Left brace (``{'').
\} Right brace (``}'').
\[ Open bracket (``['').
\] Close bracket (``]'').
\<space> Space (`` ''): doesn't terminate
argument.
\; ||
Semi-colon: doesn't terminate command. |
\" ||
Double-quote. |
\<newline> ||
Nothing: this effectively joins two |
lines together into a single line. This |
backslash feature is only provided when |
parsing Tcl commands; it is not |
supported by the Tcl_Backslash |
procedure.
\\ Backslash (``\'').
Page 6 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
\Cx Control-x (x AND octal 037), for any
ASCII x except M (see below).
\Mx Meta-x (x OR octal 200), for any ASCII
x.
\CMx Control-meta-x ((x AND octal 037) OR
octal 0200), for any ASCII x.
\ddd The digits ddd (one, two, or three of
them) give the octal value of the
character.
For example, in the command
set a \{x\[\ yz\141
the second argument to set will be ``{x[ yza''.
If a backslash is followed by something other than one of
the options described above, then the backslash is
transmitted to the argument field without any special
processing, and the Tcl scanner continues normal processing
with the next character. For example, in the command
set \*a \\\{foo
The first argument to set will be \*a and the second
argument will be \{foo.
If an argument is enclosed in braces, then backslash
sequences inside the argument are parsed but no substitution
occurs: the backslash sequence is passed through to the
argument as is, without making any special interpretation of
the characters in the backslash sequence. In particular,
backslashed braces are not counted in locating the matching
right brace that terminates the argument. For example, in
the command
set a {\{abc}
the second argument to set will be \{abc.
This backslash mechanism is not sufficient to generate
absolutely any argument structure; it only covers the most
common cases. To produce particularly complicated arguments
it will probably be easiest to use the format command along
with command substitution.
COMMAND SUMMARY
[1] A command is just a string.
Page 7 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
[2] Within a string commands are separated by newlines or
semi-colons (unless the newline or semi-colon is within
braces or brackets or is backslashed).
[3] A command consists of fields. The first field is the
name of the command, and may be abbreviated. The other
fields are strings that are passed to that command as
arguments.
[4] Fields are normally separated by white space.
[5] Braces defer interpretation of special characters. If
a field begins with a left brace, then it consists of
everything between the left brace and the matching
right brace. The braces themselves are not included in
the argument. No further processing is done on the
information between the braces.
[6] Double-quotes act the same as braces except that they
cannot be nested.
[7] If a field doesn't begin with a left brace or double-
quote, then backslash, variable, and command
substitution are done on the field. Only a single
level of processing is done: the results of one
substitution are not scanned again for further
substitutions or any other special treatment.
Substitution can occur on any field of a command,
including the command name as well as the arguments.
[8] If the first non-blank character of a command is a #,
everything from the # up through the next newline is
treated as a comment and ignored.
EXPRESSIONS
The second major interpretation applied to strings in Tcl is
as expressions. Several commands, such as expr, for, and
if, treat some of their arguments as expressions and call
the Tcl expression processor (Tcl_Expr) to evaluate them. A
Tcl expression has C-like syntax and evaluates to an integer
result. Expressions may contain integer values, variable
names in $ notation (the variables' values must be integer
strings), commands (embedded in brackets) that produce
integer string results, parentheses for grouping, and
operators. Numeric values, whether they are passed directly
or through variable or command substitution, may be
specified either in decimal (the normal case), in octal (if
the first character of the value is 0), or in hexadecimal
(if the first two characters of the value are 0x). The
valid operators are listed below, grouped in decreasing
order of precedence:
Page 8 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
- ~ ! Unary minus, bit-wise NOT, logical NOT.
* / % Multiply, divide, remainder.
+ - Add and subtract.
<< >> Left and right shift.
< > <= >= Boolean less, greater, less than or
equal, and greater than or equal. Each
operator produces 1 if the condition is
true, 0 otherwise.
== != Boolean equal and not equal. Each
operator produces a zero/one result.
& Bit-wise AND.
^ Bit-wise exclusive OR.
| Bit-wise OR.
&& Logical AND. Produces a 1 result if
both operands are non-zero, 0 otherwise.
|| Logical OR. Produces a 0 result if both
operands are zero, 1 otherwise.
See the C manual for more details on the results produced by
each operator. All of the binary operators group left-to-
right within the same precedence level. For example, the
expression
(4*2) < 7
evaluates to 0. Evaluating the expression string
($a + 3) < [set b]
will cause the values of the variables a and b to be
examined; the result will be 1 if b is greater than a by at
least 3; otherwise the result will be 0.
In general it is safest to enclose an expression in braces
when entering it in a command: otherwise, if the expression
contains any white space then the Tcl interpreter will split
it among several arguments. For example, the command
expr $a + $b
results in three arguments being passed to expr: $a, +, and
$b. In addition, if the expression isn't in braces then the
Page 9 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
Tcl interpreter will perform variable and command
substitution immediately (it will happen in the command
parser rather than in the expression parser). In many cases
the expression is being passed to a command that will
evaluate the expression later (or even many times if, for
example, the expression is to be used to decide when to exit
a loop). Usually the desired goal is to re-do the variable
or command substitutions each time the expression is
evaluated, rather than once and for all at the beginning.
For example, the command
for {set i 1} $i<=10 {set i [expr $i+1]} {...}
is probably intended to iterate over all values of i from 1
to 10. After each iteration of the body of the loop, for
will pass its second argument to the expression evaluator to
see whether or not to continue processing. Unfortunately,
in this case the value of i in the second argument will be
substituted once and for all when the for command is parsed.
If i was 0 before the for command was invoked then for's
second argument will be 0<=10 which will always evaluate to
1, even though i's value eventually becomes greater than 10.
In the above case the loop will never terminate. By placing
the expression in braces, the substitution of i's value will
be delayed; it will be re-done each time the expression is
evaluated, which is probably the desired result.
LISTS
The third major way that strings are interpreted in Tcl is
as lists. A list is just a string with a list-like
structure consisting of fields separated by white space.
For example, the string
Al Sue Anne John
is a list with four elements or fields. Lists have the same
basic structure as command strings, except that a newline
character in a list is treated as a field separator just
like space or tab. Conventions for braces and backslashes
are the same for lists as for commands. For example, the
string
a b\ c {d e {f g h}}
is a list with three elements: a, b c, and d e {f g h}.
Whenever an element is extracted from a list, the same rules
about backslashes and braces are applied as for commands.
Thus in the example above when the third element is
extracted from the list, the result is
d e {f g h}
Page 10 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
(when the field was extracted, all that happened was to
strip off the outermost layer of braces). Command
substitution is never made on a list (at least, not by the
list-processing commands; the list can always be passed to
the Tcl interpreter for evaluation).
The Tcl commands concat, foreach, index, length, list, and
range allow you to build lists, extract elements from them,
search them, and perform other list-related functions.
COMMAND RESULTS
Each command produces two results: a code and a string.
The code indicates whether the command completed
successfully or not, and the string gives additional
information. The valid codes are defined in tcl.h, and are:
TCL_OK This is the normal return code, and
indicates that the command
completed succesfully. The string
gives the command's return value.
TCL_ERROR Indicates that an error occurred;
the string gives a message
describing the error. The variable |
errorInfo will contain additional |
information describing which |
commands and procedures were being |
executed when the error occurred.
TCL_RETURN Indicates that the return command
has been invoked, and that the |
current procedure (or top-level |
command or source command) should |
return immediately. The string |
gives the return value for the |
procedure or command.
TCL_BREAK Indicates that the break command
has been invoked, so the innermost
loop should abort immediately. The
string should always be empty.
TCL_CONTINUE Indicates that the continue command
has been invoked, so the innermost
loop should go on to the next
iteration. The string should
always be empty.
Tcl programmers do not normally need to think about return
codes, since TCL_OK is almost always returned. If anything
else is returned by a command, then the Tcl interpreter
immediately stops processing commands and returns to its
Page 11 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
caller. If there are several nested invocations of the Tcl
interpreter in progress, then each nested command will
usually return the error to its caller, until eventually the
error is reported to the top-level application code. The
application will then display the error message for the
user.
In a few cases, some commands will handle certain ``error''
conditions themselves and not return them upwards. For
example, the for command checks for the TCL_BREAK code; if
it occurs, then for stops executing the body of the loop and
returns TCL_OK to its caller. The for command also handles
TCL_CONTINUE codes and the procedure interpreter handles
TCL_RETURN codes. The catch command allows Tcl programs to
catch errors and handle them without aborting command
interpretation any further.
PROCEDURES
Tcl allows you to extend the command interface by defining
procedures. A Tcl procedure can be invoked just like any
other Tcl command (it has a name and it receives one or more
arguments). The only difference is that its body isn't a
piece of C code linked into the program; it is a string
containing one or more other Tcl commands. See the proc
command for information on how to define procedures and what
happens when they are invoked.
VARIABLES
Tcl allows the definition of variables and the use of their
values either through $-style variable substitution, the set
command, or a few other mechanisms. Variables need not be
declared: a new variable will automatically be created each
time a new variable name is used. Variables may be either
global or local. If a variable name is used when a
procedure isn't being executed, then it automatically refers
to a global variable. Variable names used within a
procedure normally refer to local variables associated with
that invocation of the procedure. Local variables are
deleted whenever a procedure exits. The global command may
be used to request that a name refer to a global variable
for the duration of the current procedure (this is somewhat
analogous to extern in C).
BUILT-IN COMMANDS
The Tcl library provides the following built-in commands,
which will be available in any application using Tcl. In
addition to these built-in commands, there may be additional
commands defined by each application, plus commands defined
as Tcl procedures. In the command syntax descriptions
Page 12 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
below, optional arguments are indicated by enclosing their
names in brackets; apologies in advance for the confusion
between this descriptive use of brackets and the use of
brackets to invoke command substitution. Words in boldface
are literals that you type verbatim to Tcl. Words in
italics are meta-symbols; they act as names to refer to a
class of values that you can type.
break
This command may be invoked only inside the body of a
loop command such as for or foreach. It returns a
TCL_BREAK code to signal the innermost containing loop
command to return immediately.
case string [in] patList body patList body ...
Match string against each of the patList arguments in |
order. If one matches, then evaluate the following |
body argument by passing it recursively to the Tcl |
interpreter, and return the result of that evaluation. |
Each patList argument consists of a single pattern or |
list of patterns. Each pattern may contain any of the |
wild-cards described under string match. If a patList |
argument is default, the corresponding body will be |
evaluated if no patList matches string. If no patList |
argument matches string and no default is given, then |
the case command returns an empty string. For example, |
case abc in {a b} {format 1} default {format 2} a* {format 3}|
will return 3, |
case a in {a b} {format 1} default {format 2} a* {format 3}|
will return 1, and |
case xyz {a b} {format 1} default {format 2} a* {format 3}|
will return 2. |
catch command [varName]
The catch command may be used to prevent errors from
aborting command interpretation. Catch calls the Tcl
interpreter recursively to execute command, and always
returns a TCL_OK code, regardless of any errors that
might occur while executing command. The return value
from catch is a decimal string giving the code returned
by the Tcl interpreter after executing command. This
will be 0 (TCL_OK) if there were no errors in command;
otherwise it will have a non-zero value corresponding
to one of the exceptional return codes (see tcl.h for
the definitions of code values). If the varName
argument is given, then it gives the name of a
Page 13 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
variable; catch will set the value of the variable to
the string returned from command (either a result or an
error message).
concat arg arg ...
This command treats each argument as a list and
concatenates them into a single list. It permits any
number of arguments. For example, the command
concat a b {c d e} {f {g h}}
will return
a b c d e f {g h}
as its result.
continue
This command may be invoked only inside the body of a
loop command such as for or foreach. It returns a
TCL_CONTINUE code to signal the innermost containing
loop command to skip the remainder of the loop's body
but continue with the next iteration of the loop.
error message
Returns a TCL_ERROR code, which causes command
interpretation to be unwound. Message is a string that
is returned to the application to indicate what went
wrong. |
eval arg1 arg2 ... ||
Eval takes one or more arguments, which together |
comprise a Tcl command (or collection of Tcl commands |
separated by newlines in the usual way). Eval |
concatenates all its arguments in the same fashion as |
the concat command, passes the concatenated string to |
the Tcl interpreter recursively, and returns the result |
of that evaluation (or any error generated by it).
exec command arg1 arg2 ...[< input]
The exec command treats its command argument as the
name of a program to execute. It searches the
directories in the PATH environment variable to find an
executable file by the name command, then executes the
file, passing it an argument list consisting of command
plus all of the args. If an argument < appears
anywhere among the arguments to exec, then neither it
or the following argument is passed to command.
Instead, the following argument (input) consists of
input to the command; exec will create a pipe and use
it to pass input to command as standard input. Exec
also creates a pipe to receive command's output (both
Page 14 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
standard output and standard error). The information
received over this pipe is returned as the result of
the exec command. The exec command also looks at the
return status returned by command. Normally this
should be zero; if it is then exec returns normally.
If command returns a non-zero status, then exec will
return that code; it should be one of the ones defined
in the section ``COMMAND RESULTS'' above. If an out-of
range code is returned by the command, it will cause
command unwinding just as if TCL_ERROR had been
returned; at the outermost level of command
interpretation, the Tcl interpreter will turn the code
into TCL_ERROR, with an appropriate error message.
expr arg
Calls the expression processor to evaluate arg, and
returns the result as a decimal string.
file name option
Operate on a file or a file name. Name is the name of
a file, and option indicates what to do with the file
name. Any unique abbreviation for option is
acceptable. The valid options are:
file name dirname
Return all of the characters in name up to but not
including the last slash character. If there are
no slashes in name then return ``.''. If the last
slash in name is its first character, then return
``/''.
file name executable
Return 1 if file name is executable by the current
user, 0 otherwise.
file name exists
Return 1 if file name exists and the current user
has search privileges for the directories leading
to it, 0 otherwise.
file name extension
Return all of the characters in name after and
including the last dot in name. If there is no
dot in name then return the empty string.
file name isdirectory
Return 1 if file name is a directory, 0 otherwise.
file name isfile
Return 1 if file name is a regular file, 0
otherwise.
Page 15 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
file name owned
Return 1 if file name is owned by the current
user, 0 otherwise.
file name readable
Return 1 if file name is readable by the current
user, 0 otherwise.
file name rootname
Return all of the characters in name up to but not
including the last ``.'' character in the name.
If name doesn't contain a dot, then return name.
file name tail
Return all of the characters in name after the
last slash. If name contains no slashes then
return name.
file name writable
Return 1 if file name is writable by the current
user, 0 otherwise.
The file commands that return 0/1 results are often
used in conditional or looping commands, for example:
if {![file foo exists]} then {error {bad file name}} else {...}
for start test next body
For is a looping command, similar in structure to the C
for statement. The start, next, and body arguments
must be Tcl command strings, and test is an expression
string. The for command first invokes the Tcl
interpreter to execute first. Then it repeatedly
evaluates test as an expression; if the result is
non-zero it invokes the Tcl interpreter on body, then
invokes the Tcl interpreter on next, then repeats the
loop. The command terminates when test evaluates to 0.
If a continue command is invoked within body then any
remaining commands in the current execution of body are
skipped; processing continues by invoking the Tcl
interpreter on next, then evaluating test, and so on.
If a break command is invoked within body or next, then |
the for command will return immediately. The operation
of break and continue are similar to the corresponding
statements in C. For returns an empty string.
foreach varname list body
In this command, varname is the name of a variable,
list is a list of values to assign to varname, and body
is a collection of Tcl commands. For each field in
list (in order from left to right), foreach assigns the
Page 16 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
contents of the field to varname (as if the index
command had been used to extract the field), then calls
the Tcl interpreter to execute body. The break and
continue statements may be invoked inside body, with
the same effect as in the for command. Foreach an
empty string.
format formatString arg arg ...
This command generates a formatted string in the same
way as the C sprintf procedure (it uses sprintf in its
implementation). FormatString indicates how to format
the result, using % fields as in sprintf, and the
additional arguments, if any, provide values to be
substituted into the result. All of the sprintf
options are valid; see the sprintf man page for
details. Each arg must match the expected type from
the % field in formatString; the format command
converts each argument to the correct type (floating,
integer, etc.) before passing it to sprintf for
formatting. The only unusual conversion is for %c; in
this case the argument must be a decimal string, which
will then be converted to the corresponding ASCII
character value. Format does backslash substitution on
its formatString argument, so backslash sequences in
formatString will be handled correctly even if the
argument is in braces. The return value from format is
the formatted string.
glob filename
This command performs filename globbing, using csh |
rules. The returned value from glob is the list of |
expanded filenames.
global varname varname ...
This command is ignored unless a Tcl procedure is being
interpreted. If so, then it declares the given
varname's to be global variables rather than local
ones. For the duration of the current procedure (and
only while executing in the current procedure), any
reference to any of the varnames will be bound to a
global variable instead of a local one.
if test [then] trueBody [[else] falseBody]
The if command evaluates test as an expression (in the
same way that expr evaluates its argument). If the
result is non-zero then trueBody is called by passing
it to the Tcl interpreter. Otherwise falseBody is
executed by passing it to the Tcl interpreter. The
then and else arguments are optional ``noise words'' to
make the command easier to read. FalseBody is also
optional; if it isn't specified then the command does
nothing if test evaluates to zero. The return value
Page 17 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
from if is the value of the last command executed in
trueBody or falseBody, or the empty string if test
evaluates to zero and falseBody isn't specified.
index value index [chars]
Extract an element from a list or a character from a
string. If the chars keyword isn't specified, then
index treats value as a list and returns the index'th
field from it. In extracting the field, index observes
the same rules concerning braces and backslashes as the
Tcl command interpreter; however, variable
substitution and command substitution do not occur. If
index is greater than or equal to the number of
elements in value, then the empty string is returned.
If the chars keyword is specified (or any abbreviation
of it), then value is treated as a string and the
command returns the index'th character from it (or the
empty string if there aren't at least index+1
characters in the string). Index 0 refers to the first
element or character of value.
info option arg arg ...
Provide information about various internals to the Tcl
interpreter. The legal option's (which may be
abbreviated) are:
info args procname
Returns a list containing the names of the
arguments to procedure procname, in order.
Procname must be the name of a Tcl command
procedure.
info body procname
Returns the body of procedure procname. Procname
must be the name of a Tcl command procedure.
info commands [pattern]
If pattern isn't specified, returns a list of |
names of all the Tcl commands, including both the |
built-in commands written in C and the command |
procedures defined using the proc command. If |
pattern is specified, only those names matching |
pattern are returned. Matching is determined |
using the same rules as for string match.
info cmdcount
Returns a count of the total number of commands
that have been invoked in this interpreter.
info default procname arg varname
Procname must be the name of a Tcl command
procedure and arg must be the name of an argument
Page 18 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
to that procedure. If arg doesn't have a default
value then the command returns 0. Otherwise it
returns 1 and places the default value of arg into
variable varname.
info globals [pattern]
If pattern isn't specified, returns a list of all |
the names of currently-defined global variables. |
If pattern is specified, only those names matching |
pattern are returned. Matching is determined |
using the same rules as for string match. |
info level [number] ||
If number is not specified, this command returns a |
number giving the stack level of the invoking |
procedure, or 0 if the command is invoked at top- |
level. If number is specified, then the result is |
a list consisting of the name and arguments for |
the procedure call at level number on the stack. |
If number is positive then it selects a particular |
stack level (1 refers to the top-most active |
procedure, 2 to the procedure it called, and so |
on); otherwise it gives a level relative to the |
current level (0 refers to the current procedure, |
-1 to its caller, and so on). See the uplevel |
command for more information on what stack levels |
mean. |
info locals [pattern] ||
If pattern isn't specified, returns a list of all |
the names of currently-defined local variables, |
including arguments to the current procedure, if |
any. If pattern is specified, only those names |
matching pattern are returned. Matching is |
determined using the same rules as for string |
match. |
info procs [pattern] ||
If pattern isn't specified, returns a list of all |
the names of Tcl command procedures. If pattern |
is specified, only those names matching pattern |
are returned. Matching is determined using the |
same rules as for string match. |
info tclversion ||
Returns the version number for this version of Tcl |
in the form x.y, where changes to x represent |
major changes with probable incompatibilities and |
changes to y represent small enhancements and bug |
fixes that retain backward compatibility.
info vars
Page 19 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
Returns a list of all the names of currently-
visible variables, including both locals and
currently-visible globals.
length value [chars]
If chars isn't specified, treats value as a list and
returns the number of elements in the list. If chars
is specified (or any abbreviation of it), then length
treats value as a string and returns the number of
characters in it (not including the terminating null
character).
list arg1 arg2 ...
This command returns a list comprised of all the args.
Braces and backslashes get added as necessary, so that
the index command may be used on the result to re-
extract the original arguments, and also so that eval
may be used to execute the resulting list, with arg1
comprising the command's name and the other args
comprising its arguments. List produces slightly
different results than concat: concat removes one
level of grouping before forming the list, while list
works directly from the original arguments. For
example, the command
list a b {c d e} {f {g h}}
will return
a b {c d e} {f {g h}}
while concat with the same arguments will return
a b c d e f {g h}
print string [file [append]]
Print the string argument. If no file is specified |
then string is output to the standard output file. If |
file is specified, then string is output to that file. |
If the append option is given, then string is appended |
to file; otherwise any existing contents of file are |
discarded before string is written to the file.
proc name args body
The proc command creates a new Tcl command procedure,
name, replacing any existing command there may have
been by that name. Whenever the new command is
invoked, the contents of body will be executed by the
Tcl interpreter. Args specifies the formal arguments
to the procedure. It consists of a list, possibly
empty, each of whose elements specifies one argument.
Page 20 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
Each argument specifier is also a list with either one
or two fields. If there is only a single field in the
specifier, then it is the name of the argument; if
there are two fields, then the first is the argument
name and the second is its default value. braces and
backslashes may be used in the usual way to specify
complex default values.
When name is invoked, a local variable will be created
for each of the formal arguments to the procedure; its
value will be the value of corresponding argument in
the invoking command or the argument's default value.
Arguments with default values need not be specified in
a procedure invocation. However, there must be enough
actual arguments for all the formal arguments that
don't have defaults, and there must not be any extra
actual arguments. There is one special case to permit
procedures with variable numbers of arguments. If the
last formal argument has the name args, then a call to
the procedure may contain more actual arguments than
the procedure has formals. In this case, all of the
actual arguments starting at the one that would be
assigned to args are combined into a list (as if the
list command had been used); this combined value is
assigned to the local variable args.
When body is being executed, variable names normally
refer to local variables, which are created
automatically when referenced and deleted when the
procedure returns. One local variable is automatically
created for each of the procedure's arguments. Global
variables can only be accessed by invoking the global
command.
The proc command returns the null string. When a
procedure is invoked, the procedure's return value is
the value specified in a return command. If the
procedure doesn't execute an explicit return, then its
return value is the value of the last command executed
in the procedure's body. If an error occurs while
executing the procedure body, then the procedure-as-a-
whole will return that same error.
range value first last [chars]
Return a range of fields or characters from value. If
the chars keyword isn't specified, then value must be a
list and range will return a new list consisting of
elements first through last, inclusive. The special
keyword end may be specified for last; in this case all
the elements of value starting at first are returned.
If the chars keyword, or any abbreviation of it, is
specified, then range treats value as a character
Page 21 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
string and returns characters first through last of it,
inclusive. Once again, the end keyword may be used for
last. In both cases if a last value is specified
greater than the size of value it is equivalent to
specifying end; if last is less than first then an
empty string is returned. Note: ``range value first
first'' does not always produce the same results as
``index value first'' (although it often does for
simple fields that aren't enclosed in braces); it
does, however, produce exactly the same results as
``list [index value first]''
rename oldName newName
Rename the command that used to be called oldName so |
that it is now called newName. If newName is an empty |
string (e.g. {}) then oldName is deleted. The rename |
command returns an empty string as result.
return [value]
Return immediately from the current procedure (or top- |
level command or source command), with value as the
return value. If value is not specified, an empty
string will be returned as result.
scan string format varname1 varname2 ...
This command parses fields from an input string in the
same fashion as the C sscanf procedure. String gives
the input to be parsed and format indicates how to
parse it, using % fields as in sscanf. All of the
sscanf options are valid; see the sscanf man page for
details. Each varname gives the name of a variable;
when a field is scanned from string, the result is
converted back into a string and assigned to the
corresponding varname. The only unusual conversion is
for %c; in this case, the character value is converted
to a decimal string, which is then assigned to the
corresponding varname. |
set varname [value] ||
If value isn't specified, then return the current value |
of varname. If value is specified, then set the value
of varname to value, creating a new variable if one
doesn't already exist. If no procedure is active, then
varname refers to a global variable. If a procedure is
active, then varname refers to a parameter or local
variable of the procedure, unless the global command
has been invoked to declare varname to be global.
source fileName
Read file fileName and pass the contents to the Tcl
interpreter as a sequence of commands to execute in the
normal fashion. The return value of source is the
Page 22 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
return value of the last command executed from the
file. If an error occurs in executing the contents of
the file, then the source command will return that
error. If a return command is invoked from within the |
file, the remainder of the file will be skipped and the |
source command will return normally with the result |
from the return command.
string option a b
Perform a string operation on the two operands a and b,
based on option. The possible options are:
string compare a b
Perform a character-by-character comparison of
strings a and b, in the same way as the C strcmp
procedure. Return -1, 0, or 1, depending on
whether a is lexicographically less than, equal
to, or greater than b.
string first a b
Search b for a sequence of characters that exactly
match the characters in a. If found, return the
index of the first character in the first such
match within b. If not found, return -1.
string last a b
Search b for a sequence of characters that exactly
match the characters in a. If found, return the
index of the first character in the last such
match within b. If there is no match, then return
-1.
string match pattern string ||
See if pattern matches string; return 1 if it |
does, 0 if it doesn't. Matching is done in a |
fashion similar to that used by the C-shell. For |
the two strings to match, their contents must be |
identical except that the following special |
sequences may appear in pattern: |
* ||
Matches any sequence of characters in |
string, including a null string. |
? ||
Matches any single character in string. |
[chars] ||
Matches any character in the set given |
by chars. If a sequence of the form x-y |
appears in chars, then any character |
between x and y, inclusive, will match. |
Page 23 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
\x ||
Matches the single character x. This |
provides a way of avoiding the special |
interpretation of the characters *?[]\ |
in pattern. |
Unique abbreviations for option are acceptable.
time command [count]
This command will call the Tcl interpreter count times
to execute command (or once if count isn't specified).
It will then return a string of the form
503 microseconds per iteration
which indicates the average amount of time required per
iteration, in microseconds. Time is measured in
elapsed time, not CPU time.
uplevel level command command ...
All of the command arguments are concatenated as if |
they had been passed to concat and the result is |
evaluated in the variable context indicated by level. |
Uplevel returns the result of that evaluation. If |
level is zero, then top-level context is used (all |
variable names refer to global variables). If level is |
a positive number, then it is treated as a stack level: |
1 refers to the topmost active procedure, 2 to the |
procedure it called, and so on. If level is a negative |
number, then it is treated as a level relative to the |
current procedure. For example, a level of -1 refers |
to the procedure that called the one invoking the |
uplevel command (which is top-level if the procedure |
invoking uplevel is at level 1). The uplevel command |
causes the invoking procedure to disappear from the |
procedure calling stack while the command is being |
executed. For example, suppose procedure x is at level |
3 and invokes the command |
uplevel -1 {set a 43; c} |
where c is another Tcl procedure. The set command will |
modify variable a in x's caller, and c will execute at |
level 3, as if called from x's caller. If it in turn |
executes the command |
uplevel -1 {set a 42} |
then the set command will modify the same variable a in |
x's caller: the procedure x does not appear to be on |
the call stack when c is executing. The command ``info |
level'' may be used to obtain the level of the current |
Page 24 (printed 2/26/90)
Tcl(tcl) AMIGA 1.3 Tcl(tcl)
procedure. Uplevel makes it possible to implement new |
control constructs as Tcl procedures (for example, |
uplevel could be used to implement the while construct |
as a Tcl procedure).
BUILT-IN VARIABLES |
The following global variables are created and managed |
automatically by the Tcl library. These variables should |
normally be treated as read-only by application-specific |
code and by users. |
errorInfo ||
After an error has occurred, this string will contain |
two or more lines identifying the Tcl commands and |
procedures that were being executed when the most |
recent error occurred.
AUTHOR
John Ousterhout, University of California at Berkeley
(ouster@sprite.berkeley.edu)
Page 25 (printed 2/26/90)
Tcl_Backslash(tcl) AMIGA 1.3 Tcl_Backslash(tcl)
NAME
Tcl_Backslash - parse a backslash sequence
SYNOPSIS
#include <tcl.h>
char
Tcl_Backslash(src, countPtr)
ARGUMENTS
char*src(in)
Pointer to a string starting with a backslash.
int*countPtr(out)
If countPtr isn't NULL, *countPtr gets filled in with number
of characters in the backslash sequence, including the
backslash character.
DESCRIPTION
This is a utility procedure used by several of the Tcl
commands. It parses a backslash sequence and returns the
single character corresponding to the sequence.
Tcl_Backslash modifies *countPtr to contain the number of
characters in the backslash sequence. If src doesn't point
to a backslash sequence understood by Tcl, then
Tcl_Backslash returns a backslash as its result and
*countPtr gets set to 1 (in this case the backslash
character should not get any special treatment).
See the Tcl manual entry for information on the valid
backslash sequences. All of the sequences described in the
Tcl manual entry are supported by Tcl_Backslash except |
backslash-newline, which is not understood.
KEYWORDS
backslash, parse
Page 1 (printed 2/26/90)
Tcl_CreateCommand(tcl) AMIGA 1.3 Tcl_CreateCommand(tcl)
NAME
Tcl_CreateCommand - define an application-specific command
binding
SYNOPSIS
#include <tcl.h>
Tcl_CreateCommand(interp, cmdName, proc, clientData, deleteProc)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in
which to create new
command.
char *cmdName (in) Name of new
command.
Tcl_CreateCommand
makes a copy of
this value for its
own use.
int (*proc)() (in) Implementation of
new command: proc
will be called
whenever cmdName is
invoked as a
command.
ClientData clientData (in) Arbitrary one-word
value to pass to
proc and
deleteProc.
void (*deleteProc)() (in) Procedure to call
before cmdName is
deleted from the
interpreter; allows
for command-
specific cleanup.
If NULL, then no
procedure is called
before the command
is deleted.
DESCRIPTION
Tcl_CreateCommand defines a new command in interp and
associates it with procedure proc such that whenever cmdName
is invoked as a Tcl command (via a call to Tcl_Eval) the Tcl
interpreter will call proc to process the command. If there
is already a command cmdName associated with the
interpreter, it is deleted. Proc should have the following
Page 1 (printed 2/26/90)
Tcl_CreateCommand(tcl) AMIGA 1.3 Tcl_CreateCommand(tcl)
structure:
int
proc(clientData, interp, argc, argv)
ClientData clientData;
Tcl_Interp *interp;
int argc;
char *argv[];
{
}
The clientData and interp parameters are copies of the
clientData and interp arguments given to Tcl_CreateCommand.
Typically, clientData points to an application-specific data
structure that describes what to do when the command
procedure is invoked. Argc and argv describe the arguments
to the command, argc giving the number of arguments
(including the command name) and argv giving the values of
the arguments as strings. The argv array will contain
argc+1 values; the first argc values point to the argument
strings, and the last value is NULL.
Proc must return an integer code that is either TCL_OK,
TCL_ERROR, TCL_RETURN, TCL_BREAK, or TCL_CONTINUE. See the
Tcl overview man page for details on what these codes mean.
Most normal commands will only return TCL_OK or TCL_ERROR.
In addition, proc must set interp->result to point to a
string value; in the case of a TCL_OK return code this gives
the result of the command, and in the case of TCL_ERROR it
gives an error message. The Tcl_Return procedure provides
an easy interface for setting the return value; for
complete details on how the interp->result field is managed,
see the Tcl_Interp man page. Before invoking a command
procedure, Tcl_Eval sets interp->result to point to an empty
string, so simple commands can return an empty result by
doing nothing at all.
The contents of the argv array are copies made by the Tcl
interpreter for the use of proc. Proc may alter any of the
strings in argv. However, the argv array is recycled as
soon as proc returns, so proc must not set interp->result to
point anywhere within the argv values (call Tcl_Return with
status TCL_VOLATILE if you want to return something from the
argv array).
DeleteProc will be invoked when (if) cmdName is deleted.
This can occur through a call to Tcl_DeleteCommand or
Tcl_DeleteInterp, or by replacing cmdName in another call to
Tcl_CreateCommand. DeleteProc is invoked before the command
is deleted, and gives the application an opportunity to
release any structures associated with the command.
DeleteProc should have the following form:
void
deleteProc(clientData)
Page 2 (printed 2/26/90)
Tcl_CreateCommand(tcl) AMIGA 1.3 Tcl_CreateCommand(tcl)
ClientData clientData;
{
}
The clientData argument will be the same as the clientData
argument passed to Tcl_CreateCommand.
KEYWORDS
bind, command, create, interpreter
Page 3 (printed 2/26/90)
Tcl_CreateInterp(tcl) AMIGA 1.3 Tcl_CreateInterp(tcl)
NAME
Tcl_CreateInterp - set up a new Tcl command interpreter
SYNOPSIS
#include <tcl.h>
Tcl_Interp *
Tcl_CreateInterp()
DESCRIPTION
Tcl_CreateInterp creates a new interpreter structure and
returns a token for it. The token is required in calls to
most other Tcl procedures, such as Tcl_CreateCommand,
Tcl_Eval, and Tcl_DeleteInterp. Clients are only allowed to
access the fields of Tcl_Interp structures related to
command return values; see the Tcl_Interp and
Tcl_CreateCommand man pages for details. The new
interpreter is initialized with no defined variables and
only the built-in Tcl commands. To bind in additional
commands, call Tcl_CreateCommand.
KEYWORDS
command, create, interpreter
Page 1 (printed 2/26/90)
Tcl_CreateTrace(tcl) AMIGA 1.3 Tcl_CreateTrace(tcl)
NAME
Tcl_CreateTrace - arrange for command execution to be traced
SYNOPSIS
#include <tcl.h>
Tcl_Trace
Tcl_CreateTrace(interp, level, proc, clientData)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in which
to create new
command.
int level (in) Only commands at or
below this nesting
level will be
traced. 1 means
top-level commands
only, 2 means top-
level commands or
those that are
invoked as immediate
consequences of
executing top-level
commands (procedure
bodies, bracketed
commands, etc.) and
so on.
void (*proc)() (in) Procedure to call
for each command
that's executed.
See below for
details on the
calling sequence.
ClientData clientData (in) Arbitrary one-word
value to pass to
proc.
DESCRIPTION
Tcl_CreateTrace arranges for command tracing. From now on,
proc will be invoked before Tcl calls command procedures to
process commands in interp. The return value from
Tcl_CreateTrace is a token for the trace, which may be
passed to Tcl_DeleteTrace to remove the trace. There may be
many traces in effect simultaneously for the same command
interpreter.
Proc should have the following structure:
Page 1 (printed 2/26/90)
Tcl_CreateTrace(tcl) AMIGA 1.3 Tcl_CreateTrace(tcl)
void
proc(clientData, interp, level, command, cmdProc, cmdClientData, argc, argv)
ClientData clientData;
Tcl_Interp *interp;
int level;
char *command;
int (*cmdProc)();
ClientData cmdClientData;
int argc;
char *argv[];
{
}
The clientData and interp parameters are copies of the
corresponding arguments given to Tcl_CreateTrace.
ClientData typically points to an application-specific data
structure that describes what to do when proc is invoked.
Level gives the nesting level of the command (1 for top-
level commands passed to Tcl_Eval by the application, 2 for
the next-level commands passed to Tcl_Eval as part of
parsing or interpreting level-1 commands, and so on).
Command points to a string containing the text of the
command, before any argument substitution. CmdProc contains
the address of the command procedure that will be called to
process the command (i.e. the proc argument of some previous
call to Tcl_CreateCommand) and cmdClientData contains the
associated client data for cmdProc (the clientData value
passed to Tcl_CreateCommand). Argc and argv give the final
argument information that will be passed to cmdProc, after
command, variable, and backslash substitution. Proc must
not modify the command or argv strings.
Tracing will only occur for commands at nesting level less
than or equal to the level parameter (i.e. the level
parameter to proc will always be less than or equal to the
level parameter to Tcl_CreateTrace).
Calls to proc will be made by the Tcl parser immediately
before it calls the command procedure for the command
(cmdProc). This occurs after argument parsing and
substitution, so tracing for substituted commands occurs
before tracing of the commands containing the substitutions.
If there is a syntax error in a command, or if there is no
command procedure associated with a command name, then no
tracing will occur for that command. If a string passed to
Tcl_Eval contains multiple commands (bracketed, or on
different lines) then multiple calls to proc will occur, one
for each command. The command string for each of these
trace calls will reflect only a single command, not the
entire string passed to Tcl_Eval.
KEYWORDS
Page 2 (printed 2/26/90)
Tcl_CreateTrace(tcl) AMIGA 1.3 Tcl_CreateTrace(tcl)
command, create, interpreter, trace
Page 3 (printed 2/26/90)
Tcl_DeleteCommand(tcl) AMIGA 1.3 Tcl_DeleteCommand(tcl)
NAME
Tcl_DeleteCommand - remove a command from a Tcl interpreter
SYNOPSIS
#include <tcl.h>
Tcl_DeleteCommand(interp, cmdName)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in which to
delete command.
char *cmdName (in) Name of command to be
deleted.
DESCRIPTION
This procedure deletes a command from a command interpreter.
Once the call completes, attempts to invoke cmdName in
interp will result in errors. If cmdName isn't bound as a
command in interp then Tcl_DeleteCommand does nothing.
There are no restrictions on cmdName: it may refer to a
built-in command, an application-specific command, or a Tcl
procedure.
KEYWORDS
command, delete, interpreter
Page 1 (printed 2/26/90)
Tcl_DeleteInterp(tcl) AMIGA 1.3 Tcl_DeleteInterp(tcl)
NAME
Tcl_DeleteInterp - destroy a Tcl command interpreter
SYNOPSIS
#include <tcl.h>
Tcl_DeleteInterp(interp)
ARGUMENTS
Tcl_Interp *interp (in) Token for interpreter to be
destroyed.
DESCRIPTION
This procedure destroys a command interpreter and releases
all of the resources associated with it, including
variables, procedures, and application-specific command
bindings. After Tcl_DeleteInterp returns the caller should
never again use the interp token.
KEYWORDS
command, delete, interpreter
Page 1 (printed 2/26/90)
Tcl_DeleteTrace(tcl) AMIGA 1.3 Tcl_DeleteTrace(tcl)
NAME
Tcl_DeleteTrace - remove a previously-established command
trace
SYNOPSIS
#include <tcl.h>
Tcl_DeleteTrace(interp, trace)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter containing
trace.
Tcl_Trace trace (in) Token for trace to be
removed (return value from
previous call to
Tcl_CreateTrace).
DESCRIPTION
This procedure removes a trace, so that no future calls will
be made to the procedure associated with the trace. After
Tcl_DeleteTrace returns, the caller should never again use
the trace token.
KEYWORDS
delete, interpreter, trace
Page 1 (printed 2/26/90)
Tcl_Eval(tcl) AMIGA 1.3 Tcl_Eval(tcl)
NAME
Tcl_Eval - execute a Tcl command string
SYNOPSIS
#include <tcl.h>
int
Tcl_Eval(interp, cmd, flags, termPtr)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in which to
execute the command.
String result will be
stored in interp-
>result.
char *cmd (in) Command (or sequence of
commands) to execute.
char flags (in) Either TCL_BRACKET_TERM
or 0. If 0, then |
Tcl_Eval will process |
commands from cmd until |
it reaches the null |
character at the end of |
the string; newlines |
will be treated as |
command separators. If |
TCL_BRACKET_TERM, then |
Tcl_Eval will process |
comands from cmd until |
either it reaches a null |
character or it |
encounters a close |
bracket that isn't |
backslashed or enclosed |
in braces, at which |
point it will return; |
newlines will treated as |
white space, not as |
command separators. |
Under normal conditions, |
flags should be 0.
char **termPtr (out) If termPtr is non-NULL, |
Tcl_Eval fills in |
*termPtr with the |
address of the character |
just after the last one |
in the last command |
successfully executed |
(normally the null |
Page 1 (printed 2/26/90)
Tcl_Eval(tcl) AMIGA 1.3 Tcl_Eval(tcl)
character at the end of |
cmd). If an error |
occurs in the first |
command in cmd, then |
*termPtr will be set to |
cmd.
DESCRIPTION
Tcl_Eval parses commands from cmd and executes them in order
until either an error occurs or Tcl_Eval reaches a
terminating character (']' or ' ', depending on the value of
flags). The return value from Tcl_Eval is one of the Tcl
return codes TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, or
TCL_CONTINUE, and interp->result will point to a string with
additional information (result value or error message).
This return information corresponds to the last command
executed from cmd.
During the processing of a command it is legal to make
nested calls to Tcl_Eval (this is how conditionals, loops,
and procedures are implemented). If a code other than
TCL_OK is returned from a nested Tcl_Eval invocation, then
the caller should normally return immediately, passing that
same return code back to its caller, and so on until the
top-level application is reached. A few commands, like for,
will check for certain return codes, like TCL_BREAK and
TCL_CONTINUE, and process them specially without returning.
Tcl_Eval keeps track of how many nested Tcl_Eval invocations
are in progress for interp. If a code of TCL_RETURN,
TCL_BREAK, or TCL_CONTINUE is about to be returned from the
topmost Tcl_Eval invocation for interp, then Tcl_Eval
converts the return code to TCL_ERROR and sets interp-
>result to point to an error message indicating that the
return, break, or continue command was invoked in an
inappropriate place. This means that top-level applications
should never see a return code from Tcl_Eval other then
TCL_OK or TCL_ERROR.
KEYWORDS
command, execute, interpreter
Page 2 (printed 2/26/90)
Tcl_Expr(tcl) AMIGA 1.3 Tcl_Expr(tcl)
NAME
Tcl_Expr - evaluate an expression
SYNOPSIS
#include <tcl.h>
int
Tcl_Expr(interp, string, valuePtr)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in whose
context to evaluate string.
char *string (in) Expression to be evaluated.
int *valuePtr (out) The expression's (integer)
value will be stored here.
DESCRIPTION
Tcl_Expr is a utility procedure used by several of the Tcl
commands. Given a string whose contents are an expression
of the form accepted by the expr command, this procedure
evaluates the expression and returns the integer result in
*valuePtr. Normally Tcl_Expr returns TCL_OK as its result.
However, if the expression contains a syntax error then
Tcl_Expr returns TCL_ERROR and sets interp->result to point
to an error message in the usual fashion. Tcl_Expr may make
nested calls to Tcl_Eval while parsing the expression; if
any of these calls returns an error then Tcl_Expr will
return that same error information. If an error is
returned, then *valuePtr will not be modified.
KEYWORDS
evaluate, expression
Page 1 (printed 2/26/90)
Tcl_GetVar(tcl) AMIGA 1.3 Tcl_GetVar(tcl)
NAME
Tcl_GetVar - return the value of a Tcl variable
SYNOPSIS
#include <tcl.h>
char *
Tcl_GetVar(interp, varName, global)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in which to
check for variable.
char *varName (in) Name of desired variable.
int global (in) If non-zero, then insist
that varName be interpreted
as a global variable
regardless of whether a
procedure invocation is in
progress.
DESCRIPTION
Tcl_GetVar is a utility procedure used by several of the Tcl
commands. It returns the value of variable varName in
interpreter interp. If there isn't a Tcl command procedure
being interpreted right now, or if global is non-zero, then
varName is always treated as the name of a global variable.
Otherwise, if a procedure is being interpreted, then varName
will be treated as a local variable name, unless it has been
declared global using the global command. If no variable by
the name varName exists right now, then the empty string is
returned.
KEYWORDS
interpreter, global, local, variable
Page 1 (printed 2/26/90)
Tcl_Interp(tcl) AMIGA 1.3 Tcl_Interp(tcl)
NAME
Tcl_Interp - client-visible fields of interpreter structures
SYNOPSIS
#include <tcl.h>
typedef struct {
char *result;
int dynamic;
int errorLine;
} Tcl_Interp;
DESCRIPTION
The Tcl_CreateInterp procedure returns a pointer to a
Tcl_Interp structure. This pointer is then passed into
other Tcl procedures to process commands in the interpreter
and perform other operations on the interpreter.
Interpreter structures contain many many fields that are
used by Tcl, but only three that may be accessed by clients:
result and dynamic. These fields are used by Tcl command
procedures to return strings that form part of the result of
each command. When Tcl_Eval returns, the string pointed to
be the result field will be used by Tcl_Eval's caller as a
return value or error message.
The easiest way for command procedures to manipulate the
result and dynamic fields is to call Tcl_Return; Tcl_Return
will hide all the details of managing these fields. The
description below is for those procedures that manipulate
the fields directly.
Whenever a command procedure returns, it must ensure that
the result field of its interpreter points to the string
being returned by the command. Normally, these strings are
assumed to be statically allocated; in this case, the
dynamic field must be zero. As an alternative, a command
procedure may dynamically allocate its return value and
store a pointer to it in interp->result. In this case, the
command procedure must also set interp->dynamic to non-zero.
If interp->dynamic is non-zero, then Tcl will free the space
pointed to by interp->result before it invokes the next
command. If a client procedure overwrites interp->result
field when interp->dynamic is non-zero, then it is
responsible for freeing the old interp->result. Once again,
if clients use the Tcl_Result procedure to manage these
fields, they need not worry about these issues.
As part of processing each command, Tcl_Eval initializes
interp->result and interp->dynamic just before calling the
command procedure for the command. The dynamic field will
be initialized to zero, and interp->result will point to an
Page 1 (printed 2/26/90)
Tcl_Interp(tcl) AMIGA 1.3 Tcl_Interp(tcl)
empty string. Commands that do not return any value can
simply leave the fields alone. Furthermore, the empty
string pointed to by result is actually part of an array of
TCL_RESULT_SIZE characters (approximately 200). If a
command wishes to return a short string, it can simply copy
it to the area pointed to by interp->result. Or, it can use
the sprintf procedure to generate a short result string at
the location pointed to by interp->result.
If a command procedure calls a lower-level procedure that
sets interp->result and interp->dynamic (such as a recursive
instance of Tcl_Eval), then the command procedure must reset
interp->result if it wishes to return a value different than
that returned by the lower-level procedure. As part of
resetting interp->result, it must free the space if interp-
>dynamic is set. Once again, the easiest way to make sure
this gets done right is to call Tcl_Result.
The errorLine field is valid only after Tcl_Eval returns a |
TCL_ERROR return code. In this situation the errorLine |
field identifies the line number of the command being |
executed when the error occurred. The line numbers are |
relative to the command being executed: 1 means the first |
line of the command passed to Tcl_Eval, 2 means the second |
line, and so on. ErrorLine should not normally be modified |
except by Tcl_Eval.
KEYWORDS
dynamic, interpreter, result
Page 2 (printed 2/26/90)
Tcl_Merge(tcl) AMIGA 1.3 Tcl_Merge(tcl)
NAME
Tcl_Merge - generate a Tcl list from a collection of strings
SYNOPSIS
#include <tcl.h>
char *
Tcl_Merge(argc, argv)
ARGUMENTS
int argc (in) Number of strings.
char *argv[] (in) Array of strings to combine
into list. Must have argc
entries.
DESCRIPTION
Tcl_Merge is a utility procedure used by several of the Tcl
commands. Given a collection of strings, it generates a
result string that has proper list structure, such that the
index Tcl command may be used to extract out the original
strings. In order to do this, Tcl_Merge may have to add
braces and/or backslashes. The result string is dynamically
allocated using malloc(); the caller must eventually
release the space using free().
KEYWORDS
list, strings
Page 1 (printed 2/26/90)
Tcl_Return(tcl) AMIGA 1.3 Tcl_Return(tcl)
NAME
Tcl_Return - set up a Tcl result string
SYNOPSIS
#include <tcl.h>
Tcl_Return(interp, string, status)
ARGUMENTS
Tcl_Interp *interp (out) Interpreter for which a
return value is to be
established.
char *string (in) String value to be
returned, or NULL.
int status (in) Indicates the nature of
string. Must be either
TCL_STATIC, TCL_DYNAMIC, or
TCL_VOLATILE.
DESCRIPTION
Tcl_Return is a convenience routine used by several of the
Tcl commands. It arranges for string to be the return
string for the current Tcl command in interp. If status is
TCL_STATIC it means that string refers to an area of static
storage that is guaranteed to remain untouched until at
least the next call to Tcl_Eval. If status is TCL_DYNAMIC
it means that string was allocated with a call to malloc()
and is now the property of the Tcl system. Tcl_Return will
arrange for the string's storage to be released by calling
free() when it is no longer needed. The third possibility
is for status to be TCL_VOLATILE. This means that string
points to an area of memory that is likely to be overwritten
when Tcl_Return returns. In this case Tcl_Return makes a
copy of the string and arranges for the copy to be the
return string for the current Tcl command.
If string is NULL, then status is ignored and Tcl_Return
re-initializes interp's result to point to the pre-allocated
result area, with an empty string in the result area.
In any of the above cases, if interp holds a dynamically-
allocated result at the time of the Tcl_Return call, the old
result's storage is released by calling free().
KEYWORDS
command, result, return value, interpreter
Page 1 (printed 2/26/90)
Tcl_SetVar(tcl) AMIGA 1.3 Tcl_SetVar(tcl)
NAME
Tcl_SetVar - change the value of a Tcl variable
SYNOPSIS
#include <tcl.h>
Tcl_SetVar(interp, varName, newValue, global)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in which to
change variable.
char *varName (in) Name of variable.
char *newValue (in) New value for varName
int global (in) If non-zero, then insist on
interpreting varName as a
global variable, regardless
of whether a procedure
invocation is in progress.
DESCRIPTION
This is a utility procedure used by many of the Tcl
commands. It changes the value of variable varName in
interpreter interp, such that future calls to Tcl_GetVar
will return newValue as the value of varName. Tcl_SetVar
uses the same rules for selecting a global or local variable
as Tcl_GetVar. If varName doesn't already exist, then a new
variable is created. Tcl_SetVar copies both varName and
newValue into its own private storage, so the caller may
change the contents of these strings after Tcl_SetVar
returns without affecting the variable's value.
KEYWORDS
interpreter, variable
Page 1 (printed 2/26/90)
Tcl_SplitList(tcl) AMIGA 1.3 Tcl_SplitList(tcl)
NAME
Tcl_SplitList - break a Tcl list up into fields
SYNOPSIS
#include <tcl.h>
int
Tcl_SplitList(interp, list, argcPtr, argvPtr)
ARGUMENTS
Tcl_Interp *interp (out) Interpreter to use for
error reporting.
char *list (in) Pointer to a string with
proper list structure.
int *argcPtr (out) Filled in with number of
elements in list.
char ***argvPtr (out) *argvPtr will be filled in
with the address of an
array of pointers to the
strings that are the
extracted elements of
list. There will be
*argcPtr valid entries in
the array.
DESCRIPTION
Tcl_SplitList is the inverse of Tcl_Merge. Given a list, it
extracts all of the elements of the list and returns an
array of pointers to them using argcPtr and argvPtr. While
extracting the arguments, Tcl_SplitList obeys the usual
rules for backslash substitutions and braces. The area of
memory pointed to by *argvPtr is dynamically allocated; in
addition to the array of pointers, it also holds copies of
all the list elements. It is the caller's responsibility to
free up all of this storage by calling
free((char *) *argvPtr)
when the list elements are no longer needed.
Tcl_SplitList normally returns TCL_OK, which means the list
was successfully parsed. If there was a syntax error in
list, then TCL_ERROR is returned and interp->result will
point to an error message describing the problem.
KEYWORDS
list, split, strings
Page 1 (printed 2/26/90)
Tcl_SplitList(tcl) AMIGA 1.3 Tcl_SplitList(tcl)
Page 2 (printed 2/26/90)
Tcl_StringMatch(tcl) AMIGA 1.3 Tcl_StringMatch(tcl)
NAME |
Tcl_StringMatch - test whether a string matches a pattern |
SYNOPSIS |
#include <tcl.h> |
int |
Tcl_StringMatch(string, pattern) |
ARGUMENTS |
char *string (in) ||
String to test. |
char *pattern (in) ||
Pattern to match against |
string. May contain |
special characters from |
the set *?\[]. |
DESCRIPTION |
This utility procedure determines whether a string matches a |
given pattern. If it does, then Tcl_StringMatch returns 1. |
Otherwise Tcl_StringMatch returns 0. The algorithm used for |
matching is the same algorithm used in the ``string match'' |
Tcl command and is similar to the algorithm used by the C- |
shell for file name matching; see the Tcl manual entry for |
details. |
KEYWORDS |
match, pattern, string
Page 1 (printed 2/26/90)
Tcl_WatchInterp(tcl) AMIGA 1.3 Tcl_WatchInterp(tcl)
NAME |
Tcl_WatchInterp - arrange for callback when interpreter is |
deleted. |
SYNOPSIS |
#include <tcl.h> |
Tcl_WatchInterp(interp, proc, clientData) |
ARGUMENTS |
Tcl_Interp *interp (in) ||
Interpreter whose |
deletion should be |
monitored. |
char *cmdName (in) ||
Name of new |
command. |
void (*proc)() (in) ||
Procedure to invoke |
just before interp |
is deleted. |
ClientData clientData (in) ||
Arbitrary one-word |
value to pass to |
proc. |
DESCRIPTION |
Tcl_WatchInterp arranges for proc to be called by |
Tcl_DeleteInterp if/when interp is deleted at some future |
time. Proc will be invoked just before the interpreter is |
deleted, but the interpreter will still be valid at the time |
of the call. Proc should have the following structure: |
void |
proc(clientData, interp) |
ClientData clientData; |
Tcl_Interp *interp; |
{ |
} |
The clientData and interp parameters are copies of the |
clientData and interp arguments given to Tcl_WatchInterp. |
Typically, clientData points to an application-specific data |
structure that proc uses to perform cleanup when an |
interpreter is about to go away. Proc does not return a |
value. |
KEYWORDS |
callback, delete, interpreter
Page 1 (printed 2/26/90)